<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Math functions - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="Functions for performing various mathematical operations such as rounding, exponentiation, squaring, etc." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Math Functions</h1>
<p>Functions for performing various mathematical operations such as rounding, exponentiation, squaring, etc.</p>

<h2 id="toc">Table of Contents</h2>
<ul>
  <li><a href="#General">General Math</a>
    <ul>
      <li><a href="#Abs">Abs</a>: Returns the absolute value of a number.</li>
      <li><a href="#Ceil">Ceil</a>: Returns a number rounded up to the nearest integer.</li>
      <li><a href="#Exp">Exp</a>: Returns e raised to the <em>N</em>th power.</li>
      <li><a href="#Floor">Floor</a>: Returns a number rounded down to the nearest integer.</li>
      <li><a href="#Log">Log</a>: Returns the logarithm (base 10) of a number.</li>
      <li><a href="#Ln">Ln</a>: Returns the natural logarithm (base e) of a number.</li>
      <li><a href="#Max">Max</a> <span class="ver">[v1.1.27+]</span>: Returns the highest value of one or more numbers.</li>
      <li><a href="#Min">Min</a> <span class="ver">[v1.1.27+]</span>: Returns the lowest value of one or more numbers.</li>
      <li><a href="#Mod">Mod</a>: Returns the remainder of a division.</li>
      <li><a href="#Round">Round</a>: Returns a number rounded to <em>N</em> decimal places.</li>
      <li><a href="#Sqrt">Sqrt</a>: Returns the square root of a number.</li>
    </ul>
  </li>
  <li><a href="#Trigonometry">Trigonometry</a>
    <ul>
      <li><a href="#Sin">Sin</a>: Returns the trigonometric sine of a number.</li>
      <li><a href="#Cos">Cos</a>: Returns the trigonometric cosine of a number.</li>
      <li><a href="#Tan">Tan</a>: Returns the trigonometric tangent of a number.</li>
      <li><a href="#ASin">ASin</a>: Returns the arcsine (the number whose sine is the specified number) in radians.</li>
      <li><a href="#ACos">ACos</a>: Returns the arccosine (the number whose cosine is the specified number) in radians.</li>
      <li><a href="#ATan">ATan</a>: Returns the arctangent (the number whose tangent is the specified number) in radians.</li>
    </ul>
  </li>
  <li><a href="#Errors">Error-handling</a></li>
</ul>

<h2 id="General">General Math</h2>

<h3 id="Abs">Abs</h3>
<p>Returns the absolute value of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Abs</span>(Number)</pre>
<p>The return value is the same type as <em>Number</em> (integer or floating point).</p>
<pre class="NoIndent">MsgBox, % Abs(-1.2) <em>; Returns 1.2</em></pre>

<h3 id="Ceil">Ceil</h3>
<p>Returns <em>Number</em> rounded up to the nearest integer (without any .00 suffix).</p>
<pre class="Syntax">Value := <span class="func">Ceil</span>(Number)</pre>
<pre class="NoIndent">MsgBox, % Ceil(1.2)  <em>; Returns 2</em>
MsgBox, % Ceil(-1.2) <em>; Returns -1</em></pre>

<h3 id="Exp">Exp</h3>
<p>Returns e (which is approximately 2.71828182845905) raised to the <em>N</em>th power.</p>
<pre class="Syntax">Value := <span class="func">Exp</span>(N)</pre>
<p><em>N</em> may be negative and may contain a decimal point. To raise  numbers other than e to a power, use the <a href="../Variables.htm#pow">** operator</a>.</p>
<pre class="NoIndent">MsgBox, % Exp(1.2) <em>; Returns 3.320117</em></pre>

<h3 id="Floor">Floor</h3>
<p>Returns <em>Number</em> rounded down to the nearest integer (without any .00 suffix).</p>
<pre class="Syntax">Value := <span class="func">Floor</span>(Number)</pre>
<pre class="NoIndent">MsgBox, % Floor(1.2)  <em>; Returns 1</em>
MsgBox, % Floor(-1.2) <em>; Returns -2</em></pre>

<h3 id="Log">Log</h3>
<p>Returns the logarithm (base 10) of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Log</span>(Number)</pre>
<p>The result is formatted as <a href="SetFormat.htm">floating point</a>. If <em>Number</em> is negative, an empty string is returned.</p>
<pre class="NoIndent">MsgBox, % Log(1.2) <em>; Returns 0.079181</em></pre>

<h3 id="Ln">Ln</h3>
<p>Returns the natural logarithm (base e) of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Ln</span>(Number)</pre>
<p>The result is formatted as <a href="SetFormat.htm">floating point</a>. If <em>Number</em> is negative, an empty string is returned.</p>
<pre class="NoIndent">MsgBox, % Ln(1.2) <em>; Returns 0.182322</em></pre>

<h3 id="Max">Max <span class="ver">[v1.1.27+]</span></h3>
<p>Returns the highest value of one or more numbers.</p>
<pre class="Syntax">Value := <span class="func">Max</span>(Number1 <span class="optional">, Number2, ...</span>)</pre>
<p>If one of the input values is non-numeric, an empty string is returned.</p>
<pre class="NoIndent">MsgBox, % Max(2.11, -2, 0) <em>; Returns 2.11</em></pre>
<p>You can also specify a <a href="../Functions.htm#Variadic">variadic parameter</a> to compare multiple values within an array. For example:</p>
<pre class="NoIndent">array := [1, 2, 3, 4]
MsgBox, % Max(array*) <em>; Returns 4</em>
</pre>

<h3 id="Min">Min <span class="ver">[v1.1.27+]</span></h3>
<p>Returns the lowest value of one or more numbers.</p>
<pre class="Syntax">Value := <span class="func">Min</span>(Number1 <span class="optional">, Number2, ...</span>)</pre>
<p>If one of the input values is non-numeric, an empty string is returned.</p>
<pre class="NoIndent">MsgBox, % Min(2.11, -2, 0) <em>; Returns -2</em></pre>
<p>You can also specify a <a href="../Functions.htm#Variadic">variadic parameter</a> to compare multiple values within an array. For example:</p>
<pre class="NoIndent">array := [1, 2, 3, 4]
MsgBox, % Min(array*) <em>; Returns 1</em></pre>

<h3 id="Mod">Mod</h3>
<p>Modulo. Returns the remainder when <em>Dividend</em> is divided by <em>Divisor</em>.</p>
<pre class="Syntax">Value := <span class="func">Mod</span>(Dividend, Divisor)</pre>
<p>The sign of the result is always the same as the sign of the first parameter. If either input is a floating point number, the result is also a floating point number. If the second parameter is zero, the function yields a blank result (empty string).</p>
<pre class="NoIndent">MsgBox, % Mod(7.5, 2) <em>; Returns 1.5 (2 x 3 + 1.5)</em></pre>

<h3 id="Round">Round</h3>
<p>Returns <em>Number</em> rounded to <em>N</em> decimal places.</p>
<pre class="Syntax">Value := <span class="func">Round</span>(Number <span class="optional">, N</span>)</pre>
<p>If <em>N</em> is omitted or 0, <em>Number</em> is rounded to the nearest integer:</p>
<pre class="NoIndent">MsgBox, % Round(3.14)    <em>; Returns 3</em></pre>
<p>If <em>N</em> is positive number, <em>Number</em> is rounded to <em>N</em> decimal places:</p>
<pre class="NoIndent">MsgBox, % Round(3.14, 1) <em>; Returns 3.1</em></pre>
<p>If <em>N</em> is negative, <em>Number</em> is rounded by <em>N</em> digits to the left of the decimal point:</p>
<pre class="NoIndent">MsgBox, % Round(345, -1) <em>; Returns 350</em>
MsgBox, % Round(345, -2) <em>; Returns 300</em></pre>
<p>Unlike <a href="Transform.htm">Transform Round</a>, the result has no .000 suffix whenever <em>N</em> is omitted or less than 1. <span class="ver">[v1.0.44.01+]</span>: A value of <em>N</em> greater than zero displays exactly <em>N</em> decimal places rather than obeying <a href="SetFormat.htm">SetFormat</a>. To avoid this, perform another math operation on Round()'s return value; for example: <code>Round(3.333, 1)<strong>+0</strong></code>.</p>

<h3 id="Sqrt">Sqrt</h3>
<p>Returns the square root of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Sqrt</span>(Number)</pre>
<p>The result is formatted as <a href="SetFormat.htm">floating point</a>. If <em>Number</em> is negative, the function yields a blank result (empty string).</p>
<pre class="NoIndent">MsgBox, % Sqrt(16) <em>; Returns 4</em></pre>

<h2 id="Trigonometry">Trigonometry</h2>
<p class="note"><strong>Note</strong>: To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To convert a degrees value to radians, multiply it by pi/180 (approximately 0.01745329252). The value of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.</p>

<h3 id="Sin">Sin</h3>
<p>Returns the trigonometric sine of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Sin</span>(Number)</pre>
<p><em>Number</em> must be expressed in radians.</p>
<pre class="NoIndent">MsgBox, % Sin(1.2) <em>; Returns 0.932039</em></pre>

<h3 id="Cos">Cos</h3>
<p>Returns the trigonometric cosine of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Cos</span>(Number)</pre>
<p><em>Number</em> must be expressed in radians.</p>
<pre class="NoIndent">MsgBox, % Cos(1.2) <em>; Returns 0.362358</em></pre>

<h3 id="Tan">Tan</h3>
<p>Returns the trigonometric tangent of <em>Number</em>.</p>
<pre class="Syntax">Value := <span class="func">Tan</span>(Number)</pre>
<p><em>Number</em> must be expressed in radians.</p>
<pre class="NoIndent">MsgBox, % Tan(1.2) <em>; Returns 2.572152</em></pre>

<h3 id="ASin">ASin</h3>
<p>Returns the arcsine (the number whose sine is <em>Number</em>) in radians.</p>
<pre class="Syntax">Value := <span class="func">ASin</span>(Number)</pre>
<p>If <em>Number</em> is less than -1 or greater than 1, the function yields a blank result (empty string).</p>
<pre class="NoIndent">MsgBox, % ASin(0.2) <em>; Returns 0.201358</em></pre>

<h3 id="ACos">ACos</h3>
<p>Returns the arccosine (the number whose cosine is <em>Number</em>) in radians.</p>
<pre class="Syntax">Value := <span class="func">ACos</span>(Number)</pre>
<p>If <em>Number</em> is less than -1 or greater than 1, the function yields a blank result (empty string).</p>
<pre class="NoIndent">MsgBox, % ACos(0.2) <em>; Returns 1.369438</em></pre>

<h3 id="ATan">ATan</h3>
<p>Returns the arctangent (the number whose tangent is <em>Number</em>) in radians.</p>
<pre class="Syntax">Value := <span class="func">ATan</span>(Number)</pre>
<pre class="NoIndent">MsgBox, % ATan(1.2) <em>; Returns 0.876058</em></pre>

<h2 id="Errors">Error-Handling</h2>
<p>Invalid operations such as divide by zero generally yield a blank result (empty string).</p>
<p><a href="#Abs">Abs</a>, <a href="#Max">Max</a>, <a href="#Min">Min</a> and <a href="#Mod">Mod</a> return an empty string if any of their incoming parameters are non-numeric. Most math functions do not perform strict type-checking, so may treat non-numeric values as zero or another number. For example, <code>Round("1.0foo")</code> produces 1. However, this is expected to change in <a href="https://www.autohotkey.com/v2/">AutoHotkey v2</a>. </p>

</body>
</html>
